feat: new docs design#2505
Conversation
Co-authored-by: Vincent <vincent@ory.sh>
aeneasr
left a comment
aeneasr
left a comment
There was a problem hiding this comment.
Sitemap wise it looks like we're all covered now! Very nice! :) So from that perspective a big ✅ from my side. Results: results.csv - 404s are expected since they're on master but not on this branch yet.
There's still a bit of clean up neccessary.
Also, I think the current canonical set up is not sustainable in the medium term, and will lead to SEO issues, because all the links are manually "hardcoded", meaning that whenever a document changes URL, they need to be manually updated, and I have a high level of confidence it will be forgotten, or maybe a copy and paste error will send google to the wrong canonical.
For that reason I would suggest to have a custom component that properly sets the canonical URL and instead of hardcoding it, generates it somehow or at least is able to verify if the linked document exists.
Something like
<Canonical doc="../network/deployment.mdx" />
instead of the manually curated
<head>
<link rel="canonical" href="https://www.ory.com/docs/network/oathkeeper" />
</head>
Regarding the canonicals, how did you verify that the canonical URLs
- are the correct document
- actually exist
?
Jay and I eye-balled that they existed in the output via the Chrome > Inspect tool |
17 participants
Preview link: https://docs-rfbjzxqwi-ory.vercel.app/docs
Summary
This PR delivers a significant redesign of the Ory documentation site, introducing a new Homepage navigation experience, a new Quick Start page, restructured content architecture, and visual design improvements. It also establishes the foundational framework for separating documentation by deployment model: Ory Network, Ory OEL, and Ory OSS.
Changes
Homepage navigation
Replaced the previous homepage with a guided navigation experience that helps technical evaluators and developers orient quickly and find the right entry point for their use case. (Aligns better with our marketing site.)
Quick Start page
Added a new Quick Start page as a dedicated onboarding path for developers getting started with Ory for the first time.
Content restructuring
Reorganized existing documentation to support clearer content hierarchy. This restructuring is a prerequisite for the deployment-model separation work.
Product overview
Added new high-level product explanations with visual elements to demonstrate how each product fits within the context of an IAM system.
Visual design enhancements
Updated layout, typography, and component styling throughout the portal for improved readability and consistency. Introduced product color association.
Deployment model framework
Introduced the structural scaffolding to separate documentation by deployment context — Ory Network, Ory OEL, and Ory OSS — enabling product-specific content targeting in follow-on PRs.
What's not included
Full content separation by deployment model is out of scope for this PR. This change puts the framework in place; content migration and product-specific pages will follow.
Complete alignment on product names is out of the scope of this PR.
TESTING
New feature documentation (last few months)
Verify your new content appears in the redesigned navigation (docs/sidebar.ts). If it doesn't appear, add it to the /docs/sidebar.ts.
NOTE: There are several new sidebar files located within the /docs folder; if your content was added to the previous sidebar.ts file located in /src that file is no longer in use.
Content is complete
Verify that your product area contains the expected full set of content. The restructure may have affected navigation visibility for some pages.
Broken links
Spot-check links in your product area. Internal navigation files were significantly changed in this redesign.
Checklist
If this pull request addresses a security vulnerability,
I confirm that I got approval (please contact security@ory.com) from the maintainers to push the changes.
Summary by CodeRabbit
New Features
Documentation
Updates
Infrastructure